#####################################################################
# Product:      KnowledgeEngine (Plone Edition)
#
# File:         Editlet.py
#
# Copyright:    Copyright (c) 2004, Faulkner Technologies
#
# Author:       Brian Oliver
#
# Description:  This file defines the Editlet interface,
#               which specifies the basic functionality of a 
#               mechanism that may be used to edit properties.
#
#               An Editlet is a component that is used to 
#               provide/generate end-user property editing functionality 
#               (widgets) for an object property editor. 

#               A Property Editor for a Knowledge Engine GenericObject is 
#               constructed using a collection of appropriate 
#               (negotiated) Editlets for each property in the said object.
#
# See Also:     PropertyRefleciton, PropertyDefinition, PropertyAccess 
#####################################################################

#####################################################################
## KnowledgeEngine Library Imports
from Common import *
from PropertyDefinition import *

#####################################################################
## Zope Library Imports
from Globals import InitializeClass
from AccessControl import ClassSecurityInfo
from AccessControl.Role import RoleManager
 
#####################################################################
## Python Library Imports
# (none)

#####################################################################
## Editlet Interface Definition
class Editlet(RoleManager):
    """
        An interface specifying how an object property may be edited
    """

    #---------------------------------------------------------------#

    #define security
    security = ClassSecurityInfo()
    security.declareObjectPublic()
    security.setDefaultAccess("allow")
        
    #---------------------------------------------------------------#
        
    def isEditable(self, propertyDefinition, propertyAccess=None, value=None, isForConstructor=false, REQUEST=None, context=None):
        """
            ABSTRACT: Returns if the specified property may be edited.
            
            This method is called to determine if a property editlet 
            (property editor) should be generated for the specified
            object (propertyAccess) and property (propertyDefinition).  
            If false is returned a property editlet can not be generated 
            for the specified object property.

            PARAMETERS:
            
            propertyDefinition:     An object implementing the PropertyDefinition
                                    interface.  This object is used to provide
                                    and determine property syntactic and 
                                    semantic information.  

            propertyAccess:         (optiona) An object implement the PropertyAccess
                                    interface.  This object is used to 
                                    access the desired property value.  Generally
                                    a GenericObject descendant should be specifed
                                    here, although None is acceptable.
                                    
                                    (remember: GenericObject implements the 
                                    PropertyAccess interface)
                                    
            value:                  (optional) A value to use if the propertyAccess 
                                    object is not provided.

            isForConstructor        (Optional) Is the Editlet for the an
                                    object constructor.  Default is false.
                                    
            REQUEST                 (Optional) The Request Object from Zope, providing information
                                    about the context in which the editlet is required.  Default is None.
                                
            context                 (Optional) Usually the parent of the object being edited. Default is None.

            RETURN TYPE: Boolean
        """
        return true
        
    #---------------------------------------------------------------#

    def generateEditorForExtJS(self, propertyDefinition, propertyAccess=None, value=None, isForConstructor=false, REQUEST=None, context=None):
        """ Returns Javascript code to render this field using ExtJS """
        
        print "Cannot find editlet for %s (%s)" % ( str(self), propertyDefinition.getIdentity() )
        return "" # Implement in child classes!
        
    #---------------------------------------------------------------#

    def generateEditorFor(self, propertyDefinition, propertyAccess=None, value=None, isForConstructor=false, REQUEST=None, context=None):
        """
            ABSTRACT: Returns a string containing HTML that is to be used 
            as part of a Property Editor page.
            
            PRECONDITION:           isEditable(propertyDefinition, propertyAccess) 

            PARAMETERS:
            
            propertyDefinition:     An object implementing the PropertyDefinition
                                    interface.  This object is used to provide
                                    and determine property syntactic and 
                                    semantic information.  

            propertyAccess:         (optional) An object implement the PropertyAccess
                                    interface.  This object is used to 
                                    access the desired property value.  Generally
                                    a GenericObject descendant should be specifed
                                    here, although None is acceptable. If None is specified
                                    the value parameter is used as the default editing value.
                                    
                                    (remember: GenericObject implements the 
                                    PropertyAccess interface)

            value:                  (optional) A value to use if the propertyAccess 
                                    object is not provided.
                                    
            isForConstructor        (Optional) Is the Editlet for the an
                                    object constructor.  Default is false.

            REQUEST                 (Optional) The Request Object from Zope, providing information
                                    about the context in which the editlet is required.  Default is None.

            context                 (Optional) Usually the parent of the object being edited. Default is None.

            RETURN TYPE: String (of HTML)
        """

        return ""
        
    #---------------------------------------------------------------#

    def generateEditorHTMLInitialisation(self, propertyDefinition, propertyAccess=None, value=None, isForConstructor=false, REQUEST=None, context=None):
        """
            ABSTRACT: Returns a string containing html that is placed at the top of the page.
            
            PRECONDITION:           isEditable(propertyDefinition, propertyAccess) 

            PARAMETERS:
            
            propertyDefinition:     An object implementing the PropertyDefinition
                                    interface.  This object is used to provide
                                    and determine property syntactic and 
                                    semantic information.  

            propertyAccess:         (optional) An object implement the PropertyAccess
                                    interface.  This object is used to 
                                    access the desired property value.  Generally
                                    a GenericObject descendant should be specifed
                                    here, although None is acceptable. If None is specified
                                    the value parameter is used as the default editing value.
                                    
                                    (remember: GenericObject implements the 
                                    PropertyAccess interface)

            value:                  (optional) A value to use if the propertyAccess 
                                    object is not provided.
                                    
            isForConstructor        (Optional) Is the Editlet for the an
                                    object constructor.  Default is false.

            REQUEST                 (Optional) The Request Object from Zope, providing information
                                    about the context in which the editlet is required.  Default is None.

            context                 (Optional) Usually the parent of the object being edited. Default is None.

            RETURN TYPE: String (of HTML)
        """

        return ""    
        
    #---------------------------------------------------------------#

    def generateEditorJSInitialisation(self, propertyDefinition, propertyAccess=None, value=None, isForConstructor=false, REQUEST=None, context=None):
        """
            ABSTRACT: Returns a string containing Javascript that is to be used 
            as part of the Property Editor 'onload' event.
            
            PRECONDITION:           isEditable(propertyDefinition, propertyAccess) 

            PARAMETERS:
            
            propertyDefinition:     An object implementing the PropertyDefinition
                                    interface.  This object is used to provide
                                    and determine property syntactic and 
                                    semantic information.  

            propertyAccess:         (optional) An object implement the PropertyAccess
                                    interface.  This object is used to 
                                    access the desired property value.  Generally
                                    a GenericObject descendant should be specifed
                                    here, although None is acceptable. If None is specified
                                    the value parameter is used as the default editing value.
                                    
                                    (remember: GenericObject implements the 
                                    PropertyAccess interface)

            value:                  (optional) A value to use if the propertyAccess 
                                    object is not provided.
                                    
            isForConstructor        (Optional) Is the Editlet for the an
                                    object constructor.  Default is false.

            REQUEST                 (Optional) The Request Object from Zope, providing information
                                    about the context in which the editlet is required.  Default is None.

            context                 (Optional) Usually the parent of the object being edited. Default is None.

            RETURN TYPE: String (of JavaScript)
        """

        return ""    
        
    #---------------------------------------------------------------#

    def containsPropertyValue(self, propertyDefinition, REQUEST):
        """
            ABSTRACT: Determines if the provided request contains
            a value for the specified propertyDefinition.
            
            This method is used (and is useful for) determining and
            updating the values of properties from property editors.
            
            All editlet implementations must override this method.            
        """
        
        #by default we assume that a property value exists in the REQUEST
        return true
        
    #---------------------------------------------------------------#

    def updatePropertyWith(self, propertyDefinition, propertyAccess, REQUEST=None):
        """
            ABSTRACT: Attempts to update the specified property on the
            object implementing the PropertyAccess interface with the
            specified HTTP REQUEST.

            PRECONDITION:           self.containsPropertyValue(propertyDefinition, REQUEST)
            
            PARAMETERS:
            
            propertyDefinition:     An object implementing the PropertyDefinition
                                    interface.  This object is used to provide
                                    and determine property syntactic and 
                                    semantic information.  

            propertyAccess:         An object implement the PropertyAccess
                                    interface.  This object is used to 
                                    access and set the desired property value.  Generally
                                    a GenericObject descendant should be specifed
                                    here.
                                    
                                    (remember: GenericObject implements the 
                                    PropertyAccess interface)

            REQUEST:                The Zope HTTP Request object potentially 
                                    containing the necessary values that will be used
                                    to set the property value
        """

        pass
        
    #---------------------------------------------------------------#

#####################################################################
## Class Initialisation
InitializeClass(Editlet)
